home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / apr_buckets.h.z / apr_buckets.h
C/C++ Source or Header  |  2002-07-08  |  57KB  |  1,439 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54. /**
  55.  * @file apr_buckets.h
  56.  * @brief APR-UTIL Buckets/Bucket Brigades
  57.  */
  58.  
  59. #ifndef APR_BUCKETS_H
  60. #define APR_BUCKETS_H
  61.  
  62. #include "apu.h"
  63. #include "apr_network_io.h"
  64. #include "apr_file_io.h"
  65. #include "apr_general.h"
  66. #include "apr_mmap.h"
  67. #include "apr_errno.h"
  68. #include "apr_ring.h"
  69. #include "apr.h"
  70. #if APR_HAVE_SYS_UIO_H
  71. #include <sys/uio.h>    /* for struct iovec */
  72. #endif
  73. #if APR_HAVE_STDARG_H
  74. #include <stdarg.h>
  75. #endif
  76.  
  77. #ifdef __cplusplus
  78. extern "C" {
  79. #endif
  80.  
  81. /**
  82.  * @defgroup APR_Util_Bucket_Brigades Bucket Brigades
  83.  * @ingroup APR_Util
  84.  * @{ 
  85.  */
  86.  
  87. /** default bucket buffer size - 8KB minus room for memory allocator headers */
  88. #define APR_BUCKET_BUFF_SIZE 8000
  89.  
  90. typedef enum {
  91.     APR_BLOCK_READ,   /* block until data becomes available */
  92.     APR_NONBLOCK_READ /* return immediately if no data is available */
  93. } apr_read_type_e;
  94.  
  95. /**
  96.  * The one-sentence buzzword-laden overview: Bucket brigades represent
  97.  * a complex data stream that can be passed through a layered IO
  98.  * system without unnecessary copying. A longer overview follows...
  99.  *
  100.  * A bucket brigade is a doubly linked list (ring) of buckets, so we
  101.  * aren't limited to inserting at the front and removing at the end.
  102.  * Buckets are only passed around as members of a brigade, although
  103.  * singleton buckets can occur for short periods of time.
  104.  *
  105.  * Buckets are data stores of various types. They can refer to data in
  106.  * memory, or part of a file or mmap area, or the output of a process,
  107.  * etc. Buckets also have some type-dependent accessor functions:
  108.  * read, split, copy, setaside, and destroy.
  109.  *
  110.  * read returns the address and size of the data in the bucket. If the
  111.  * data isn't in memory then it is read in and the bucket changes type
  112.  * so that it can refer to the new location of the data. If all the
  113.  * data doesn't fit in the bucket then a new bucket is inserted into
  114.  * the brigade to hold the rest of it.
  115.  *
  116.  * split divides the data in a bucket into two regions. After a split
  117.  * the original bucket refers to the first part of the data and a new
  118.  * bucket inserted into the brigade after the original bucket refers
  119.  * to the second part of the data. Reference counts are maintained as
  120.  * necessary.
  121.  *
  122.  * setaside ensures that the data in the bucket has a long enough
  123.  * lifetime. Sometimes it is convenient to create a bucket referring
  124.  * to data on the stack in the expectation that it will be consumed
  125.  * (output to the network) before the stack is unwound. If that
  126.  * expectation turns out not to be valid, the setaside function is
  127.  * called to move the data somewhere safer.
  128.  *
  129.  * copy makes a duplicate of the bucket structure as long as it's
  130.  * possible to have multiple references to a single copy of the
  131.  * data itself.  Not all bucket types can be copied.
  132.  *
  133.  * destroy maintains the reference counts on the resources used by a
  134.  * bucket and frees them if necessary.
  135.  *
  136.  * Note: all of the above functions have wrapper macros (apr_bucket_read(),
  137.  * apr_bucket_destroy(), etc), and those macros should be used rather
  138.  * than using the function pointers directly.
  139.  *
  140.  * To write a bucket brigade, they are first made into an iovec, so that we
  141.  * don't write too little data at one time.  Currently we ignore compacting the
  142.  * buckets into as few buckets as possible, but if we really want good
  143.  * performance, then we need to compact the buckets before we convert to an
  144.  * iovec, or possibly while we are converting to an iovec.
  145.  */
  146.  
  147. /*
  148.  * Forward declaration of the main types.
  149.  */
  150.  
  151. typedef struct apr_bucket_brigade apr_bucket_brigade;
  152. typedef struct apr_bucket apr_bucket;
  153. typedef struct apr_bucket_alloc_t apr_bucket_alloc_t;
  154.  
  155. typedef struct apr_bucket_type_t apr_bucket_type_t;
  156. struct apr_bucket_type_t {
  157.     /**
  158.      * The name of the bucket type
  159.      */
  160.     const char *name;
  161.     /** 
  162.      * The number of functions this bucket understands.  Can not be less than
  163.      * five.
  164.      */
  165.     int num_func;
  166.     /**
  167.      * Whether the bucket contains metadata (ie, information that
  168.      * describes the regular contents of the brigade).  The metadata
  169.      * is not returned by apr_bucket_read() and is not indicated by
  170.      * the ->length of the apr_bucket itself.  In other words, an
  171.      * empty bucket is safe to arbitrarily remove if and only if it
  172.      * contains no metadata.  In this sense, "data" is just raw bytes
  173.      * that are the "content" of the brigade and "metadata" describes
  174.      * that data but is not a proper part of it.
  175.      */
  176.     enum {
  177.         /** This bucket type represents actual data to send to the client. */
  178.         APR_BUCKET_DATA = 0,
  179.         /** This bucket type represents metadata. */
  180.         APR_BUCKET_METADATA = 1
  181.     } is_metadata;
  182.     /**
  183.      * Free the private data and any resources used by the bucket (if they
  184.      *  aren't shared with another bucket).  This function is required to be
  185.      *  implemented for all bucket types, though it might be a no-op on some
  186.      *  of them (namely ones that never allocate any private data structures).
  187.      * @param data The private data pointer from the bucket to be destroyed
  188.      */
  189.     void (*destroy)(void *data);
  190.  
  191.     /**
  192.      * Read the data from the bucket. This is required to be implemented
  193.      *  for all bucket types.
  194.      * @param b The bucket to read from
  195.      * @param str A place to store the data read.  Allocation should only be
  196.      *            done if absolutely necessary. 
  197.      * @param len The amount of data read.
  198.      * @param block Should this read function block if there is more data that
  199.      *              cannot be read immediately.
  200.      */
  201.     apr_status_t (*read)(apr_bucket *b, const char **str, apr_size_t *len, 
  202.                          apr_read_type_e block);
  203.     
  204.     /**
  205.      * Make it possible to set aside the data for at least as long as the
  206.      *  given pool. Buckets containing data that could potentially die before
  207.      *  this pool (e.g. the data resides on the stack, in a child pool of
  208.      *  the given pool, or in a disjoint pool) must somehow copy, shift, or
  209.      *  transform the data to have the proper lifetime.
  210.      * @param e The bucket to convert
  211.      * @remark Some bucket types contain data that will always outlive the
  212.      *         bucket itself. For example no data (EOS and FLUSH), or the data
  213.      *         resides in global, constant memory (IMMORTAL), or the data is on
  214.      *      the heap (HEAP). For these buckets, apr_bucket_setaside_noop can
  215.      *      be used.
  216.      */
  217.     apr_status_t (*setaside)(apr_bucket *e, apr_pool_t *pool);
  218.  
  219.     /**
  220.      * Split one bucket in two at the specified position by duplicating
  221.      *  the bucket structure (not the data) and modifying any necessary
  222.      *  start/end/offset information.  If it's not possible to do this
  223.      *  for the bucket type (perhaps the length of the data is indeterminate,
  224.      *  as with pipe and socket buckets), then APR_ENOTIMPL is returned.
  225.      * @param e The bucket to split
  226.      * @param point The offset of the first byte in the new bucket
  227.      */
  228.     apr_status_t (*split)(apr_bucket *e, apr_size_t point);
  229.  
  230.     /**
  231.      * Copy the bucket structure (not the data), assuming that this is
  232.      *  possible for the bucket type. If it's not, APR_ENOTIMPL is returned.
  233.      * @param e The bucket to copy
  234.      * @param c Returns a pointer to the new bucket
  235.      */
  236.     apr_status_t (*copy)(apr_bucket *e, apr_bucket **c);
  237.  
  238. };
  239.  
  240. /**
  241.  * apr_bucket structures are allocated on the malloc() heap and
  242.  * their lifetime is controlled by the parent apr_bucket_brigade
  243.  * structure. Buckets can move from one brigade to another e.g. by
  244.  * calling APR_BRIGADE_CONCAT(). In general the data in a bucket has
  245.  * the same lifetime as the bucket and is freed when the bucket is
  246.  * destroyed; if the data is shared by more than one bucket (e.g.
  247.  * after a split) the data is freed when the last bucket goes away.
  248.  */
  249. struct apr_bucket {
  250.     /** Links to the rest of the brigade */
  251.     APR_RING_ENTRY(apr_bucket) link;
  252.     /** The type of bucket.  */
  253.     const apr_bucket_type_t *type;
  254.     /** The length of the data in the bucket.  This could have been implemented
  255.      *  with a function, but this is an optimization, because the most
  256.      *  common thing to do will be to get the length.  If the length is unknown,
  257.      *  the value of this field will be (apr_size_t)(-1).
  258.      */
  259.     apr_size_t length;
  260.     /** The start of the data in the bucket relative to the private base
  261.      *  pointer.  The vast majority of bucket types allow a fixed block of
  262.      *  data to be referenced by multiple buckets, each bucket pointing to
  263.      *  a different segment of the data.  That segment starts at base+start
  264.      *  and ends at base+start+length.  
  265.      *  If the length == (apr_size_t)(-1), then start == -1.
  266.      */
  267.     apr_off_t start;
  268.     /** type-dependent data hangs off this pointer */
  269.     void *data;    
  270.     /**
  271.      * Pointer to function used to free the bucket. This function should
  272.      * always be defined and it should be consistent with the memory
  273.      * function used to allocate the bucket. For example, if malloc() is 
  274.      * used to allocate the bucket, this pointer should point to free().
  275.      * @param e Pointer to the bucket being freed
  276.      */
  277.     void (*free)(void *e);
  278.     /** The freelist from which this bucket was allocated */
  279.     apr_bucket_alloc_t *list;
  280. };
  281.  
  282. /** A list of buckets */
  283. struct apr_bucket_brigade {
  284.     /** The pool to associate the brigade with.  The data is not allocated out
  285.      *  of the pool, but a cleanup is registered with this pool.  If the 
  286.      *  brigade is destroyed by some mechanism other than pool destruction,
  287.      *  the destroying function is responsible for killing the cleanup.
  288.      */
  289.     apr_pool_t *p;
  290.     /** The buckets in the brigade are on this list. */
  291.     /*
  292.      * The apr_bucket_list structure doesn't actually need a name tag
  293.      * because it has no existence independent of struct apr_bucket_brigade;
  294.      * the ring macros are designed so that you can leave the name tag
  295.      * argument empty in this situation but apparently the Windows compiler
  296.      * doesn't like that.
  297.      */
  298.     APR_RING_HEAD(apr_bucket_list, apr_bucket) list;
  299.     /** The freelist from which this bucket was allocated */
  300.     apr_bucket_alloc_t *bucket_alloc;
  301. };
  302.  
  303.  
  304. typedef apr_status_t (*apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx);
  305.  
  306. /**
  307.  * Wrappers around the RING macros to reduce the verbosity of the code
  308.  * that handles bucket brigades.
  309.  */
  310. /**
  311.  * The magic pointer value that indicates the head of the brigade
  312.  * @remark This is used to find the beginning and end of the brigade, eg:
  313.  * <pre>
  314.  *      while (e != APR_BRIGADE_SENTINEL(b)) {
  315.  *          ...
  316.  *          e = APR_BUCKET_NEXT(e);
  317.  *      }
  318.  * </pre>
  319.  * @param  b The brigade
  320.  * @return The magic pointer value
  321.  */
  322. #define APR_BRIGADE_SENTINEL(b)    APR_RING_SENTINEL(&(b)->list, apr_bucket, link)
  323.  
  324. /**
  325.  * Determine if the bucket brigade is empty
  326.  * @param b The brigade to check
  327.  * @return true or false
  328.  */
  329. #define APR_BRIGADE_EMPTY(b)    APR_RING_EMPTY(&(b)->list, apr_bucket, link)
  330.  
  331. /**
  332.  * Return the first bucket in a brigade
  333.  * @param b The brigade to query
  334.  * @return The first bucket in the brigade
  335.  */
  336. #define APR_BRIGADE_FIRST(b)    APR_RING_FIRST(&(b)->list)
  337. /**
  338.  * Return the last bucket in a brigade
  339.  * @param b The brigade to query
  340.  * @return The last bucket in the brigade
  341.  */
  342. #define APR_BRIGADE_LAST(b)    APR_RING_LAST(&(b)->list)
  343.  
  344. /**
  345.  * Iterate through a bucket brigade
  346.  * @param e The current bucket
  347.  * @param b The brigade to iterate over
  348.  * @remark This is the same as either:
  349.  * <pre>
  350.  *    e = APR_BRIGADE_FIRST(b);
  351.  *     while (e != APR_BRIGADE_SENTINEL(b)) {
  352.  *        ...
  353.  *         e = APR_BUCKET_NEXT(e);
  354.  *     }
  355.  *  OR
  356.  *     for (e = APR_BRIGADE_FIRST(b);
  357.  *           e != APR_BRIGADE_SENTINEL(b);
  358.  *           e = APR_BUCKET_NEXT(e)) {
  359.  *        ...
  360.  *     }
  361.  * </pre>
  362.  * @warning Be aware that you cannot change the value of e within
  363.  * the foreach loop, nor can you destroy the bucket it points to.
  364.  * Modifying the prev and next pointers of the bucket is dangerous
  365.  * but can be done if you're careful.  If you change e's value or
  366.  * destroy the bucket it points to, then APR_BRIGADE_FOREACH
  367.  * will have no way to find out what bucket to use for its next
  368.  * iteration.  The reason for this can be seen by looking closely
  369.  * at the equivalent loops given in the tip above.  So, for example,
  370.  * if you are writing a loop that empties out a brigade one bucket
  371.  * at a time, APR_BRIGADE_FOREACH just won't work for you.  Do it
  372.  * by hand, like so:
  373.  * <pre>
  374.  *      while (!APR_BRIGADE_EMPTY(b)) {
  375.  *          e = APR_BRIGADE_FIRST(b);
  376.  *          ...
  377.  *          apr_bucket_delete(e);
  378.  *      }
  379.  * </pre>
  380.  */
  381. #define APR_BRIGADE_FOREACH(e, b)                    \
  382.     APR_RING_FOREACH((e), &(b)->list, apr_bucket, link)
  383.  
  384. /**
  385.  * Insert a list of buckets at the front of a brigade
  386.  * @param b The brigade to add to
  387.  * @param e The first bucket in a list of buckets to insert
  388.  */
  389. #define APR_BRIGADE_INSERT_HEAD(b, e) do {                \
  390.     apr_bucket *ap__b = (e);                                        \
  391.     APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link);    \
  392.     } while (0)
  393.  
  394. /**
  395.  * Insert a list of buckets at the end of a brigade
  396.  * @param b The brigade to add to
  397.  * @param e The first bucket in a list of buckets to insert
  398.  */
  399. #define APR_BRIGADE_INSERT_TAIL(b, e) do {                \
  400.     apr_bucket *ap__b = (e);                    \
  401.     APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link);    \
  402.     } while (0)
  403.  
  404. /**
  405.  * Concatenate brigade b onto the end of brigade a, leaving brigade b empty
  406.  * @param a The first brigade
  407.  * @param b The second brigade
  408.  */
  409. #define APR_BRIGADE_CONCAT(a, b)                    \
  410.     APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link)
  411.  
  412. /**
  413.  * Prepend brigade b onto the beginning of brigade a, leaving brigade b empty
  414.  * @param a The first brigade
  415.  * @param b The second brigade
  416.  */
  417. #define APR_BRIGADE_PREPEND(a, b)                    \
  418.     APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link)
  419.  
  420. /**
  421.  * Insert a list of buckets before a specified bucket
  422.  * @param a The bucket to insert before
  423.  * @param b The buckets to insert
  424.  */
  425. #define APR_BUCKET_INSERT_BEFORE(a, b) do {                \
  426.     apr_bucket *ap__a = (a), *ap__b = (b);                \
  427.     APR_RING_INSERT_BEFORE(ap__a, ap__b, link);            \
  428.     } while (0)
  429.  
  430. /**
  431.  * Insert a list of buckets after a specified bucket
  432.  * @param a The bucket to insert after
  433.  * @param b The buckets to insert
  434.  */
  435. #define APR_BUCKET_INSERT_AFTER(a, b) do {                \
  436.     apr_bucket *ap__a = (a), *ap__b = (b);                \
  437.     APR_RING_INSERT_AFTER(ap__a, ap__b, link);            \
  438.     } while (0)
  439.  
  440. /**
  441.  * Get the next bucket in the list
  442.  * @param e The current bucket
  443.  * @return The next bucket
  444.  */
  445. #define APR_BUCKET_NEXT(e)    APR_RING_NEXT((e), link)
  446. /**
  447.  * Get the previous bucket in the list
  448.  * @param e The current bucket
  449.  * @return The previous bucket
  450.  */
  451. #define APR_BUCKET_PREV(e)    APR_RING_PREV((e), link)
  452.  
  453. /**
  454.  * Remove a bucket from its bucket brigade
  455.  * @param e The bucket to remove
  456.  */
  457. #define APR_BUCKET_REMOVE(e)    APR_RING_REMOVE((e), link)
  458.  
  459. /**
  460.  * Initialize a new bucket's prev/next pointers
  461.  * @param e The bucket to initialize
  462.  */
  463. #define APR_BUCKET_INIT(e)    APR_RING_ELEM_INIT((e), link)
  464.  
  465. /**
  466.  * Determine if a bucket contains metadata.  An empty bucket is
  467.  * safe to arbitrarily remove if and only if this is false.
  468.  * @param e The bucket to inspect
  469.  * @return true or false
  470.  */
  471. #define APR_BUCKET_IS_METADATA(e)    (e->type->is_metadata)
  472.  
  473. /**
  474.  * Determine if a bucket is a FLUSH bucket
  475.  * @param e The bucket to inspect
  476.  * @return true or false
  477.  */
  478. #define APR_BUCKET_IS_FLUSH(e)       (e->type == &apr_bucket_type_flush)
  479. /**
  480.  * Determine if a bucket is an EOS bucket
  481.  * @param e The bucket to inspect
  482.  * @return true or false
  483.  */
  484. #define APR_BUCKET_IS_EOS(e)         (e->type == &apr_bucket_type_eos)
  485. /**
  486.  * Determine if a bucket is a FILE bucket
  487.  * @param e The bucket to inspect
  488.  * @return true or false
  489.  */
  490. #define APR_BUCKET_IS_FILE(e)        (e->type == &apr_bucket_type_file)
  491. /**
  492.  * Determine if a bucket is a PIPE bucket
  493.  * @param e The bucket to inspect
  494.  * @return true or false
  495.  */
  496. #define APR_BUCKET_IS_PIPE(e)        (e->type == &apr_bucket_type_pipe)
  497. /**
  498.  * Determine if a bucket is a SOCKET bucket
  499.  * @param e The bucket to inspect
  500.  * @return true or false
  501.  */
  502. #define APR_BUCKET_IS_SOCKET(e)      (e->type == &apr_bucket_type_socket)
  503. /**
  504.  * Determine if a bucket is a HEAP bucket
  505.  * @param e The bucket to inspect
  506.  * @return true or false
  507.  */
  508. #define APR_BUCKET_IS_HEAP(e)        (e->type == &apr_bucket_type_heap)
  509. /**
  510.  * Determine if a bucket is a TRANSIENT bucket
  511.  * @param e The bucket to inspect
  512.  * @return true or false
  513.  */
  514. #define APR_BUCKET_IS_TRANSIENT(e)   (e->type == &apr_bucket_type_transient)
  515. /**
  516.  * Determine if a bucket is a IMMORTAL bucket
  517.  * @param e The bucket to inspect
  518.  * @return true or false
  519.  */
  520. #define APR_BUCKET_IS_IMMORTAL(e)    (e->type == &apr_bucket_type_immortal)
  521. #if APR_HAS_MMAP
  522. /**
  523.  * Determine if a bucket is a MMAP bucket
  524.  * @param e The bucket to inspect
  525.  * @return true or false
  526.  */
  527. #define APR_BUCKET_IS_MMAP(e)        (e->type == &apr_bucket_type_mmap)
  528. #endif
  529. /**
  530.  * Determine if a bucket is a POOL bucket
  531.  * @param e The bucket to inspect
  532.  * @return true or false
  533.  */
  534. #define APR_BUCKET_IS_POOL(e)        (e->type == &apr_bucket_type_pool)
  535.  
  536. /*
  537.  * General-purpose reference counting for the various bucket types.
  538.  *
  539.  * Any bucket type that keeps track of the resources it uses (i.e.
  540.  * most of them except for IMMORTAL, TRANSIENT, and EOS) needs to
  541.  * attach a reference count to the resource so that it can be freed
  542.  * when the last bucket that uses it goes away. Resource-sharing may
  543.  * occur because of bucket splits or buckets that refer to globally
  544.  * cached data. */
  545.  
  546. typedef struct apr_bucket_refcount apr_bucket_refcount;
  547. /**
  548.  * The structure used to manage the shared resource must start with an
  549.  * apr_bucket_refcount which is updated by the general-purpose refcount
  550.  * code. A pointer to the bucket-type-dependent private data structure
  551.  * can be cast to a pointer to an apr_bucket_refcount and vice versa.
  552.  */
  553. struct apr_bucket_refcount {
  554.     /** The number of references to this bucket */
  555.     int          refcount;
  556. };
  557.  
  558. /*  *****  Reference-counted bucket types  *****  */
  559.  
  560.  
  561. typedef struct apr_bucket_heap apr_bucket_heap;
  562. /**
  563.  * A bucket referring to data allocated off the heap.
  564.  */
  565. struct apr_bucket_heap {
  566.     /** Number of buckets using this memory */
  567.     apr_bucket_refcount  refcount;
  568.     /** The start of the data actually allocated.  This should never be
  569.      * modified, it is only used to free the bucket.
  570.      */
  571.     char    *base;
  572.     /** how much memory was allocated */
  573.     apr_size_t  alloc_len;
  574.     /** function to use to delete the data */
  575.     void (*free_func)(void *data);
  576. };
  577.  
  578. typedef struct apr_bucket_pool apr_bucket_pool;
  579. /**
  580.  * A bucket referring to data allocated from a pool
  581.  */
  582. struct apr_bucket_pool {
  583.     /** The pool bucket must be able to be easily morphed to a heap
  584.      * bucket if the pool gets cleaned up before all references are
  585.      * destroyed.  This apr_bucket_heap structure is populated automatically
  586.      * when the pool gets cleaned up, and subsequent calls to pool_read()
  587.      * will result in the apr_bucket in question being morphed into a
  588.      * regular heap bucket.  (To avoid having to do many extra refcount
  589.      * manipulations and b->data manipulations, the apr_bucket_pool
  590.      * struct actually *contains* the apr_bucket_heap struct that it
  591.      * will become as its first element; the two share their
  592.      * apr_bucket_refcount members.)
  593.      */
  594.     apr_bucket_heap  heap;
  595.     /** The block of data actually allocated from the pool.
  596.      * Segments of this block are referenced by adjusting
  597.      * the start and length of the apr_bucket accordingly.
  598.      * This will be NULL after the pool gets cleaned up.
  599.      */
  600.     const char *base;
  601.     /** The pool the data was allocated from.  When the pool
  602.      * is cleaned up, this gets set to NULL as an indicator
  603.      * to pool_read() that the data is now on the heap and
  604.      * so it should morph the bucket into a regular heap
  605.      * bucket before continuing.
  606.      */
  607.     apr_pool_t *pool;
  608.     /** The freelist this structure was allocated from, which is
  609.      * needed in the cleanup phase in order to allocate space on the heap
  610.      */
  611.     apr_bucket_alloc_t *list;
  612. };
  613.  
  614. #if APR_HAS_MMAP
  615. typedef struct apr_bucket_mmap apr_bucket_mmap;
  616. /**
  617.  * A bucket referring to an mmap()ed file
  618.  */
  619. struct apr_bucket_mmap {
  620.     /** Number of buckets using this memory */
  621.     apr_bucket_refcount  refcount;
  622.     /** The mmap this sub_bucket refers to */
  623.     apr_mmap_t *mmap;
  624. };
  625. #endif
  626.  
  627. typedef struct apr_bucket_file apr_bucket_file;
  628. /**
  629.  * A bucket referring to an file
  630.  */
  631. struct apr_bucket_file {
  632.     /** Number of buckets using this memory */
  633.     apr_bucket_refcount  refcount;
  634.     /** The file this bucket refers to */
  635.     apr_file_t *fd;
  636.     /** The pool into which any needed structures should
  637.      *  be created while reading from this file bucket */
  638.     apr_pool_t *readpool;
  639. #if APR_HAS_MMAP
  640.     /** Whether this bucket should be memory-mapped if
  641.      *  a caller tries to read from it */
  642.     int can_mmap;
  643. #endif /* APR_HAS_MMAP */
  644. };
  645.  
  646. typedef union apr_bucket_structs apr_bucket_structs;
  647. /**
  648.  * A union of all bucket structures so we know what
  649.  * the max size is.
  650.  */
  651. union apr_bucket_structs {
  652.     apr_bucket      b;
  653.     apr_bucket_heap heap;
  654.     apr_bucket_pool pool;
  655. #if APR_HAS_MMAP
  656.     apr_bucket_mmap mmap;
  657. #endif
  658.     apr_bucket_file file;
  659. };
  660.  
  661. /**
  662.  * The amount that apr_bucket_alloc() should allocate in the common case.
  663.  * Note: this is twice as big as apr_bucket_structs to allow breathing
  664.  * room for third-party bucket types.
  665.  */
  666. #define APR_BUCKET_ALLOC_SIZE  APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))
  667.  
  668. /*  *****  Bucket Brigade Functions  *****  */
  669. /**
  670.  * Create a new bucket brigade.  The bucket brigade is originally empty.
  671.  * @param The pool to associate with the brigade.  Data is not allocated out
  672.  *        of the pool, but a cleanup is registered.
  673.  * @return The empty bucket brigade
  674.  */
  675. APU_DECLARE(apr_bucket_brigade *) apr_brigade_create(apr_pool_t *p,
  676.                                                      apr_bucket_alloc_t *list);
  677.  
  678. /**
  679.  * destroy an entire bucket brigade.  This includes destroying all of the
  680.  * buckets within the bucket brigade's bucket list. 
  681.  * @param b The bucket brigade to destroy
  682.  */
  683. APU_DECLARE(apr_status_t) apr_brigade_destroy(apr_bucket_brigade *b);
  684.  
  685. /**
  686.  * empty out an entire bucket brigade.  This includes destroying all of the
  687.  * buckets within the bucket brigade's bucket list.  This is similar to
  688.  * apr_brigade_destroy(), except that it does not deregister the brigade's
  689.  * pool cleanup function.
  690.  * @param b The bucket brigade to clean up
  691.  * @remark Generally, you should use apr_brigade_destroy().  This function
  692.  *         can be useful in situations where you have a single brigade that
  693.  *         you wish to reuse many times by destroying all of the buckets in
  694.  *         the brigade and putting new buckets into it later.
  695.  */
  696. APU_DECLARE(apr_status_t) apr_brigade_cleanup(void *data);
  697.  
  698. /**
  699.  * Split a bucket brigade into two, such that the given bucket is the
  700.  * first in the new bucket brigade. This function is useful when a
  701.  * filter wants to pass only the initial part of a brigade to the next
  702.  * filter.
  703.  * @param b The brigade to split
  704.  * @param e The first element of the new brigade
  705.  * @return The new brigade
  706.  */
  707. APU_DECLARE(apr_bucket_brigade *) apr_brigade_split(apr_bucket_brigade *b,
  708.                                                     apr_bucket *e);
  709.  
  710. /**
  711.  * Partition a bucket brigade at a given offset (in bytes from the start of
  712.  * the brigade).  This is useful whenever a filter wants to use known ranges
  713.  * of bytes from the brigade; the ranges can even overlap.
  714.  * @param b The brigade to partition
  715.  * @param point The offset at which to partition the brigade
  716.  * @param after_point Returns a pointer to the first bucket after the partition
  717.  */
  718. APU_DECLARE(apr_status_t) apr_brigade_partition(apr_bucket_brigade *b,
  719.                                                 apr_off_t point,
  720.                                                 apr_bucket **after_point);
  721.  
  722. #if APR_NOT_DONE_YET
  723. /**
  724.  * consume nbytes from beginning of b -- call apr_bucket_destroy as
  725.  * appropriate, and/or modify start on last element 
  726.  * @param b The brigade to consume data from
  727.  * @param nbytes The number of bytes to consume
  728.  */
  729. APU_DECLARE(void) apr_brigade_consume(apr_bucket_brigade *b,
  730.                                       apr_off_t nbytes);
  731. #endif
  732.  
  733. /**
  734.  * Return the total length of the brigade.
  735.  * @param bb The brigade to compute the length of
  736.  * @param read_all Read unknown-length buckets to force a size
  737.  * @param length Returns the length of the brigade, or -1 if the brigade has
  738.  *               buckets of indeterminate length and read_all is 0.
  739.  */
  740. APU_DECLARE(apr_status_t) apr_brigade_length(apr_bucket_brigade *bb,
  741.                                              int read_all,
  742.                                              apr_off_t *length);
  743.  
  744. /**
  745.  * Take a bucket brigade and store the data in a flat char*
  746.  * @param bb The bucket brigade to create the char* from
  747.  * @param c The char* to write into
  748.  * @param len The maximum length of the char array. On return, it is the
  749.  *            actual length of the char array.
  750.  */
  751. APU_DECLARE(apr_status_t) apr_brigade_flatten(apr_bucket_brigade *bb,
  752.                                               char *c,
  753.                                               apr_size_t *len);
  754.  
  755. /**
  756.  * Creates a pool-allocated string representing a flat bucket brigade
  757.  * @param bb The bucket brigade to create the iovec from
  758.  * @param c On return, the allocated char array
  759.  * @param len On return, the length of the char array.
  760.  * @param p The pool to allocate the string from.
  761.  */
  762. APU_DECLARE(apr_status_t) apr_brigade_pflatten(apr_bucket_brigade *bb, 
  763.                                                char **c,
  764.                                                apr_size_t *len,
  765.                                                apr_pool_t *pool);
  766.  
  767. /**
  768.  * Split a brigade to represent one LF line.
  769.  * @param bbOut The bucket brigade that will have the LF line appended to.
  770.  * @param bbIn The input bucket brigade to search for a LF-line.
  771.  * @param block The blocking mode to be used to split the line.
  772.  * @param maxbytes The maximum bytes to read.  If this many bytes are seen
  773.  *                 without a LF, the brigade will contain a partial line.
  774.  */
  775. APU_DECLARE(apr_status_t) apr_brigade_split_line(apr_bucket_brigade *bbOut,
  776.                                                  apr_bucket_brigade *bbIn,
  777.                                                  apr_read_type_e block,
  778.                                                  apr_off_t maxbytes);
  779.  
  780. /**
  781.  * create an iovec of the elements in a bucket_brigade... return number 
  782.  * of elements used.  This is useful for writing to a file or to the
  783.  * network efficiently.
  784.  * @param b The bucket brigade to create the iovec from
  785.  * @param vec The iovec to create
  786.  * @param nvec The number of elements in the iovec. On return, it is the
  787.  *             number of iovec elements actually filled out.
  788.  */
  789. APU_DECLARE(apr_status_t) apr_brigade_to_iovec(apr_bucket_brigade *b, 
  790.                                                struct iovec *vec, int *nvec);
  791.  
  792. /**
  793.  * This function writes a list of strings into a bucket brigade. 
  794.  * @param b The bucket brigade to add to
  795.  * @param flush The flush function to use if the brigade is full
  796.  * @param ctx The structure to pass to the flush function
  797.  * @param va A list of strings to add
  798.  * @return APR_SUCCESS or error code.
  799.  */
  800. APU_DECLARE(apr_status_t) apr_brigade_vputstrs(apr_bucket_brigade *b,
  801.                                                apr_brigade_flush flush,
  802.                                                void *ctx,
  803.                                                va_list va);
  804.  
  805. /**
  806.  * This function writes a string into a bucket brigade.
  807.  * @param b The bucket brigade to add to
  808.  * @param flush The flush function to use if the brigade is full
  809.  * @param ctx The structure to pass to the flush function
  810.  * @param str The string to add
  811.  * @param nbyte The number of bytes to write
  812.  * @return APR_SUCCESS or error code
  813.  */
  814. APU_DECLARE(apr_status_t) apr_brigade_write(apr_bucket_brigade *b,
  815.                                             apr_brigade_flush flush, void *ctx,
  816.                                             const char *str, apr_size_t nbyte);
  817.  
  818. /**
  819.  * This function writes a string into a bucket brigade.
  820.  * @param bb The bucket brigade to add to
  821.  * @param flush The flush function to use if the brigade is full
  822.  * @param ctx The structure to pass to the flush function
  823.  * @param str The string to add
  824.  * @return APR_SUCCESS or error code
  825.  */
  826. APU_DECLARE(apr_status_t) apr_brigade_puts(apr_bucket_brigade *bb,
  827.                                            apr_brigade_flush flush, void *ctx,
  828.                                            const char *str);
  829.  
  830. /**
  831.  * This function writes a character into a bucket brigade.
  832.  * @param b The bucket brigade to add to
  833.  * @param flush The flush function to use if the brigade is full
  834.  * @param ctx The structure to pass to the flush function
  835.  * @param c The character to add
  836.  * @return APR_SUCCESS or error code
  837.  */
  838. APU_DECLARE(apr_status_t) apr_brigade_putc(apr_bucket_brigade *b,
  839.                                            apr_brigade_flush flush, void *ctx,
  840.                                            const char c);
  841.  
  842. /**
  843.  * This function writes an unspecified number of strings into a bucket brigade.
  844.  * @param b The bucket brigade to add to
  845.  * @param flush The flush function to use if the brigade is full
  846.  * @param ctx The structure to pass to the flush function
  847.  * @param ... The strings to add
  848.  * @return APR_SUCCESS or error code
  849.  */
  850. APU_DECLARE_NONSTD(apr_status_t) apr_brigade_putstrs(apr_bucket_brigade *b,
  851.                                                      apr_brigade_flush flush,
  852.                                                      void *ctx, ...);
  853.  
  854. /**
  855.  * Evaluate a printf and put the resulting string at the end 
  856.  * of the bucket brigade.
  857.  * @param b The brigade to write to
  858.  * @param flush The flush function to use if the brigade is full
  859.  * @param ctx The structure to pass to the flush function
  860.  * @param fmt The format of the string to write
  861.  * @param ... The arguments to fill out the format
  862.  * @return APR_SUCCESS or error code
  863.  */
  864. APU_DECLARE_NONSTD(apr_status_t) apr_brigade_printf(apr_bucket_brigade *b, 
  865.                                                     apr_brigade_flush flush,
  866.                                                     void *ctx,
  867.                                                     const char *fmt, ...)
  868.         __attribute__((format(printf,4,5)));
  869.  
  870. /**
  871.  * Evaluate a printf and put the resulting string at the end 
  872.  * of the bucket brigade.
  873.  * @param b The brigade to write to
  874.  * @param flush The flush function to use if the brigade is full
  875.  * @param ctx The structure to pass to the flush function
  876.  * @param fmt The format of the string to write
  877.  * @param va The arguments to fill out the format
  878.  * @return APR_SUCCESS or error code
  879.  */
  880. APU_DECLARE(apr_status_t) apr_brigade_vprintf(apr_bucket_brigade *b, 
  881.                                               apr_brigade_flush flush,
  882.                                               void *ctx,
  883.                                               const char *fmt, va_list va);
  884.  
  885. /*  *****  Bucket freelist functions *****  */
  886. /**
  887.  * Create a bucket allocator.
  888.  * @param p Pool to allocate the allocator from [note: this is only
  889.  *          used to allocate internal structures of the allocator, NOT
  890.  *          to allocate the memory handed out by the allocator]
  891.  * @warning The allocator must never be used by more than one thread at a time.
  892.  */
  893. APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create(apr_pool_t *p);
  894.  
  895. /**
  896.  * Destroy a bucket allocator.
  897.  * @param list The allocator to be destroyed
  898.  */
  899. APU_DECLARE_NONSTD(void) apr_bucket_alloc_destroy(apr_bucket_alloc_t *list);
  900.  
  901. /**
  902.  * Allocate memory for use by the buckets.
  903.  * @param size The amount to allocate.
  904.  * @param list The allocator from which to allocate the memory.
  905.  */
  906. APU_DECLARE_NONSTD(void *) apr_bucket_alloc(apr_size_t size, apr_bucket_alloc_t *list);
  907.  
  908. /**
  909.  * Free memory previously allocated with apr_bucket_alloc().
  910.  * @param block The block of memory to be freed.
  911.  */
  912. APU_DECLARE_NONSTD(void) apr_bucket_free(void *block);
  913.  
  914.  
  915. /*  *****  Bucket Functions  *****  */
  916. /**
  917.  * Free the resources used by a bucket. If multiple buckets refer to
  918.  * the same resource it is freed when the last one goes away.
  919.  * @see apr_bucket_delete()
  920.  * @param e The bucket to destroy
  921.  */
  922. #define apr_bucket_destroy(e) do {                    \
  923.         (e)->type->destroy((e)->data);                    \
  924.         (e)->free(e);                            \
  925.     } while (0)
  926.  
  927. /**
  928.  * Delete a bucket by removing it from its brigade (if any) and then
  929.  * destroying it.
  930.  * @remark This mainly acts as an aid in avoiding code verbosity.  It is
  931.  * the preferred exact equivalent to:
  932.  * <pre>
  933.  *      APR_BUCKET_REMOVE(e);
  934.  *      apr_bucket_destroy(e);
  935.  * </pre>
  936.  * @param e The bucket to delete
  937.  */
  938. #define apr_bucket_delete(e) do {                    \
  939.         APR_BUCKET_REMOVE(e);                        \
  940.         apr_bucket_destroy(e);                        \
  941.     } while (0)
  942.  
  943. /**
  944.  * read the data from the bucket
  945.  * @param e The bucket to read from
  946.  * @param str The location to store the data in
  947.  * @param len The amount of data read
  948.  * @param block Whether the read function blocks
  949.  */
  950. #define apr_bucket_read(e,str,len,block) (e)->type->read(e, str, len, block)
  951.  
  952. /**
  953.  * Setaside data so that stack data is not destroyed on returning from
  954.  * the function
  955.  * @param e The bucket to setaside
  956.  */
  957. #define apr_bucket_setaside(e,p) (e)->type->setaside(e,p)
  958.  
  959. /**
  960.  * Split one bucket in two.
  961.  * @param e The bucket to split
  962.  * @param point The offset to split the bucket at
  963.  */
  964. #define apr_bucket_split(e,point) (e)->type->split(e, point)
  965.  
  966. /**
  967.  * Copy a bucket.
  968.  * @param e The bucket to copy
  969.  * @param c Returns a pointer to the new bucket
  970.  */
  971. #define apr_bucket_copy(e,c) (e)->type->copy(e, c)
  972.  
  973. /* Bucket type handling */
  974.  
  975. /**
  976.  * This function simply returns APR_SUCCESS to denote that the bucket does
  977.  * not require anything to happen for its setaside() function. This is
  978.  * appropriate for buckets that have "immortal" data -- the data will live
  979.  * at least as long as the bucket.
  980.  * @param data The bucket to setaside
  981.  * @param pool The pool defining the desired lifetime of the bucket data
  982.  * @return APR_SUCCESS
  983.  */ 
  984. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_noop(apr_bucket *data,
  985.                                                           apr_pool_t *pool);
  986.  
  987. /**
  988.  * A place holder function that signifies that the setaside function was not
  989.  * implemented for this bucket
  990.  * @param data The bucket to setaside
  991.  * @param pool The pool defining the desired lifetime of the bucket data
  992.  * @return APR_ENOTIMPL
  993.  */ 
  994. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_notimpl(apr_bucket *data,
  995.                                                              apr_pool_t *pool);
  996.  
  997. /**
  998.  * A place holder function that signifies that the split function was not
  999.  * implemented for this bucket
  1000.  * @param data The bucket to split
  1001.  * @param point The location to split the bucket
  1002.  * @return APR_ENOTIMPL
  1003.  */ 
  1004. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_split_notimpl(apr_bucket *data,
  1005.                                                           apr_size_t point);
  1006.  
  1007. /**
  1008.  * A place holder function that signifies that the copy function was not
  1009.  * implemented for this bucket
  1010.  * @param e The bucket to copy
  1011.  * @param c Returns a pointer to the new bucket
  1012.  * @return APR_ENOTIMPL
  1013.  */
  1014. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_copy_notimpl(apr_bucket *e,
  1015.                                                          apr_bucket **c);
  1016.  
  1017. /**
  1018.  * A place holder function that signifies that this bucket does not need
  1019.  * to do anything special to be destroyed.  That's only the case for buckets
  1020.  * that either have no data (metadata buckets) or buckets whose data pointer
  1021.  * points to something that's not a bucket-type-specific structure, as with
  1022.  * simple buckets where data points to a string and pipe buckets where data
  1023.  * points directly to the apr_file_t.
  1024.  * @param data The bucket data to destroy
  1025.  */ 
  1026. APU_DECLARE_NONSTD(void) apr_bucket_destroy_noop(void *data);
  1027.  
  1028. /**
  1029.  * There is no apr_bucket_destroy_notimpl, because destruction is required
  1030.  * to be implemented (it could be a noop, but only if that makes sense for
  1031.  * the bucket type)
  1032.  */
  1033.  
  1034. /* There is no apr_bucket_read_notimpl, because it is a required function
  1035.  */
  1036.  
  1037.  
  1038. /* All of the bucket types implemented by the core */
  1039. /**
  1040.  * The flush bucket type.  This signifies that all data should be flushed to
  1041.  * the next filter.  The flush bucket should be sent with the other buckets.
  1042.  */
  1043. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_flush;
  1044. /**
  1045.  * The EOS bucket type.  This signifies that there will be no more data, ever.
  1046.  * All filters MUST send all data to the next filter when they receive a
  1047.  * bucket of this type
  1048.  */
  1049. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_eos;
  1050. /**
  1051.  * The FILE bucket type.  This bucket represents a file on disk
  1052.  */
  1053. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_file;
  1054. /**
  1055.  * The HEAP bucket type.  This bucket represents a data allocated from the
  1056.  * heap.
  1057.  */
  1058. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_heap;
  1059. #if APR_HAS_MMAP
  1060. /**
  1061.  * The MMAP bucket type.  This bucket represents an MMAP'ed file
  1062.  */
  1063. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_mmap;
  1064. #endif
  1065. /**
  1066.  * The POOL bucket type.  This bucket represents a data that was allocated
  1067.  * from a pool.  IF this bucket is still available when the pool is cleared,
  1068.  * the data is copied on to the heap.
  1069.  */
  1070. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pool;
  1071. /**
  1072.  * The PIPE bucket type.  This bucket represents a pipe to another program.
  1073.  */
  1074. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pipe;
  1075. /**
  1076.  * The IMMORTAL bucket type.  This bucket represents a segment of data that
  1077.  * the creator is willing to take responsability for.  The core will do
  1078.  * nothing with the data in an immortal bucket
  1079.  */
  1080. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_immortal;
  1081. /**
  1082.  * The TRANSIENT bucket type.  This bucket represents a data allocated off
  1083.  * the stack.  When the setaside function is called, this data is copied on
  1084.  * to the heap
  1085.  */
  1086. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_transient;
  1087. /**
  1088.  * The SOCKET bucket type.  This bucket represents a socket to another machine
  1089.  */
  1090. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_socket;
  1091.  
  1092.  
  1093. /*  *****  Simple buckets  *****  */
  1094.  
  1095. /**
  1096.  * Split a simple bucket into two at the given point.  Most non-reference
  1097.  * counting buckets that allow multiple references to the same block of
  1098.  * data (eg transient and immortal) will use this as their split function
  1099.  * without any additional type-specific handling.
  1100.  * @param b The bucket to be split
  1101.  * @param point The offset of the first byte in the new bucket
  1102.  * @return APR_EINVAL if the point is not within the bucket;
  1103.  *         APR_ENOMEM if allocation failed;
  1104.  *         or APR_SUCCESS
  1105.  */
  1106. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_split(apr_bucket *b,
  1107.                                                          apr_size_t point);
  1108.  
  1109. /**
  1110.  * Copy a simple bucket.  Most non-reference-counting buckets that allow
  1111.  * multiple references to the same block of data (eg transient and immortal)
  1112.  * will use this as their copy function without any additional type-specific
  1113.  * handling.
  1114.  * @param a The bucket to copy
  1115.  * @param b Returns a pointer to the new bucket
  1116.  * @return APR_ENOMEM if allocation failed;
  1117.  *         or APR_SUCCESS
  1118.  */
  1119. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_copy(apr_bucket *a,
  1120.                                                         apr_bucket **b);
  1121.  
  1122.  
  1123. /*  *****  Shared, reference-counted buckets  *****  */
  1124.  
  1125. /**
  1126.  * Initialize a bucket containing reference-counted data that may be
  1127.  * shared. The caller must allocate the bucket if necessary and
  1128.  * initialize its type-dependent fields, and allocate and initialize
  1129.  * its own private data structure. This function should only be called
  1130.  * by type-specific bucket creation functions.
  1131.  * @param b The bucket to initialize
  1132.  * @param data A pointer to the private data structure
  1133.  *             with the reference count at the start
  1134.  * @param start The start of the data in the bucket
  1135.  *              relative to the private base pointer
  1136.  * @param length The length of the data in the bucket
  1137.  * @return The new bucket, or NULL if allocation failed
  1138.  */
  1139. APU_DECLARE(apr_bucket *) apr_bucket_shared_make(apr_bucket *b, void *data,
  1140.                                  apr_off_t start, 
  1141.                                                  apr_size_t length);
  1142.  
  1143. /**
  1144.  * Decrement the refcount of the data in the bucket. This function
  1145.  * should only be called by type-specific bucket destruction functions.
  1146.  * @param data The private data pointer from the bucket to be destroyed
  1147.  * @return TRUE or FALSE; TRUE if the reference count is now
  1148.  *         zero, indicating that the shared resource itself can
  1149.  *         be destroyed by the caller.
  1150.  */
  1151. APU_DECLARE(int) apr_bucket_shared_destroy(void *data);
  1152.  
  1153. /**
  1154.  * Split a bucket into two at the given point, and adjust the refcount
  1155.  * to the underlying data. Most reference-counting bucket types will
  1156.  * be able to use this function as their split function without any
  1157.  * additional type-specific handling.
  1158.  * @param b The bucket to be split
  1159.  * @param point The offset of the first byte in the new bucket
  1160.  * @return APR_EINVAL if the point is not within the bucket;
  1161.  *         APR_ENOMEM if allocation failed;
  1162.  *         or APR_SUCCESS
  1163.  */
  1164. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_split(apr_bucket *b,
  1165.                                                          apr_size_t point);
  1166.  
  1167. /**
  1168.  * Copy a refcounted bucket, incrementing the reference count. Most
  1169.  * reference-counting bucket types will be able to use this function
  1170.  * as their copy function without any additional type-specific handling.
  1171.  * @param a The bucket to copy
  1172.  * @param b Returns a pointer to the new bucket
  1173.  * @return APR_ENOMEM if allocation failed;
  1174.            or APR_SUCCESS
  1175.  */
  1176. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_copy(apr_bucket *a,
  1177.                                                         apr_bucket **b);
  1178.  
  1179.  
  1180. /*  *****  Functions to Create Buckets of varying types  *****  */
  1181. /*
  1182.  * Each bucket type foo has two initialization functions:
  1183.  * apr_bucket_foo_make which sets up some already-allocated memory as a
  1184.  * bucket of type foo; and apr_bucket_foo_create which allocates memory
  1185.  * for the bucket, calls apr_bucket_make_foo, and initializes the
  1186.  * bucket's list pointers. The apr_bucket_foo_make functions are used
  1187.  * inside the bucket code to change the type of buckets in place;
  1188.  * other code should call apr_bucket_foo_create. All the initialization
  1189.  * functions change nothing if they fail.
  1190.  */
  1191.  
  1192. /**
  1193.  * Create an End of Stream bucket.  This indicates that there is no more data
  1194.  * coming from down the filter stack.  All filters should flush at this point.
  1195.  * @param list The freelist from which this bucket should be allocated
  1196.  * @return The new bucket, or NULL if allocation failed
  1197.  */
  1198. APU_DECLARE(apr_bucket *) apr_bucket_eos_create(apr_bucket_alloc_t *list);
  1199.  
  1200. /**
  1201.  * Make the bucket passed in an EOS bucket.  This indicates that there is no 
  1202.  * more data coming from down the filter stack.  All filters should flush at 
  1203.  * this point.
  1204.  * @param b The bucket to make into an EOS bucket
  1205.  * @return The new bucket, or NULL if allocation failed
  1206.  */
  1207. APU_DECLARE(apr_bucket *) apr_bucket_eos_make(apr_bucket *b);
  1208.  
  1209. /**
  1210.  * Create a flush  bucket.  This indicates that filters should flush their
  1211.  * data.  There is no guarantee that they will flush it, but this is the
  1212.  * best we can do.
  1213.  * @param list The freelist from which this bucket should be allocated
  1214.  * @return The new bucket, or NULL if allocation failed
  1215.  */
  1216. APU_DECLARE(apr_bucket *) apr_bucket_flush_create(apr_bucket_alloc_t *list);
  1217.  
  1218. /**
  1219.  * Make the bucket passed in a FLUSH  bucket.  This indicates that filters 
  1220.  * should flush their data.  There is no guarantee that they will flush it, 
  1221.  * but this is the best we can do.
  1222.  * @param b The bucket to make into a FLUSH bucket
  1223.  * @return The new bucket, or NULL if allocation failed
  1224.  */
  1225. APU_DECLARE(apr_bucket *) apr_bucket_flush_make(apr_bucket *b);
  1226.  
  1227. /**
  1228.  * Create a bucket referring to long-lived data.
  1229.  * @param buf The data to insert into the bucket
  1230.  * @param nbyte The size of the data to insert.
  1231.  * @param list The freelist from which this bucket should be allocated
  1232.  * @return The new bucket, or NULL if allocation failed
  1233.  */
  1234. APU_DECLARE(apr_bucket *) apr_bucket_immortal_create(const char *buf, 
  1235.                                                      apr_size_t nbyte,
  1236.                                                      apr_bucket_alloc_t *list);
  1237.  
  1238. /**
  1239.  * Make the bucket passed in a bucket refer to long-lived data
  1240.  * @param b The bucket to make into a IMMORTAL bucket
  1241.  * @param buf The data to insert into the bucket
  1242.  * @param nbyte The size of the data to insert.
  1243.  * @return The new bucket, or NULL if allocation failed
  1244.  */
  1245. APU_DECLARE(apr_bucket *) apr_bucket_immortal_make(apr_bucket *b, 
  1246.                                                    const char *buf, 
  1247.                                                    apr_size_t nbyte);
  1248.  
  1249. /**
  1250.  * Create a bucket referring to data on the stack.
  1251.  * @param buf The data to insert into the bucket
  1252.  * @param nbyte The size of the data to insert.
  1253.  * @param list The freelist from which this bucket should be allocated
  1254.  * @return The new bucket, or NULL if allocation failed
  1255.  */
  1256. APU_DECLARE(apr_bucket *) apr_bucket_transient_create(const char *buf, 
  1257.                                                       apr_size_t nbyte,
  1258.                                                       apr_bucket_alloc_t *list);
  1259.  
  1260. /**
  1261.  * Make the bucket passed in a bucket refer to stack data
  1262.  * @param b The bucket to make into a TRANSIENT bucket
  1263.  * @param buf The data to insert into the bucket
  1264.  * @param nbyte The size of the data to insert.
  1265.  * @return The new bucket, or NULL if allocation failed
  1266.  */
  1267. APU_DECLARE(apr_bucket *) apr_bucket_transient_make(apr_bucket *b, 
  1268.                                                     const char *buf,
  1269.                                                     apr_size_t nbyte);
  1270.  
  1271. /**
  1272.  * Create a bucket referring to memory on the heap. If the caller asks
  1273.  * for the data to be copied, this function always allocates 4K of
  1274.  * memory so that more data can be added to the bucket without
  1275.  * requiring another allocation. Therefore not all the data may be put
  1276.  * into the bucket. If copying is not requested then the bucket takes
  1277.  * over responsibility for free()ing the memory.
  1278.  * @param buf The buffer to insert into the bucket
  1279.  * @param nbyte The size of the buffer to insert.
  1280.  * @param free_func Function to use to free the data; NULL indicates that the
  1281.  *                  bucket should make a copy of the data
  1282.  * @param list The freelist from which this bucket should be allocated
  1283.  * @return The new bucket, or NULL if allocation failed
  1284.  */
  1285. APU_DECLARE(apr_bucket *) apr_bucket_heap_create(const char *buf, 
  1286.                                                  apr_size_t nbyte,
  1287.                                                  void (*free_func)(void *data),
  1288.                                                  apr_bucket_alloc_t *list);
  1289. /**
  1290.  * Make the bucket passed in a bucket refer to heap data
  1291.  * @param b The bucket to make into a HEAP bucket
  1292.  * @param buf The buffer to insert into the bucket
  1293.  * @param nbyte The size of the buffer to insert.
  1294.  * @param free_func Function to use to free the data; NULL indicates that the
  1295.  *                  bucket should make a copy of the data
  1296.  * @return The new bucket, or NULL if allocation failed
  1297.  */
  1298. APU_DECLARE(apr_bucket *) apr_bucket_heap_make(apr_bucket *b, const char *buf,
  1299.                                                apr_size_t nbyte,
  1300.                                                void (*free_func)(void *data));
  1301.  
  1302. /**
  1303.  * Create a bucket referring to memory allocated from a pool.
  1304.  *
  1305.  * @param buf The buffer to insert into the bucket
  1306.  * @param length The number of bytes referred to by this bucket
  1307.  * @param pool The pool the memory was allocated from
  1308.  * @param list The freelist from which this bucket should be allocated
  1309.  * @return The new bucket, or NULL if allocation failed
  1310.  */
  1311. APU_DECLARE(apr_bucket *) apr_bucket_pool_create(const char *buf, 
  1312.                                                  apr_size_t length,
  1313.                                                  apr_pool_t *pool,
  1314.                                                  apr_bucket_alloc_t *list);
  1315.  
  1316. /**
  1317.  * Make the bucket passed in a bucket refer to pool data
  1318.  * @param b The bucket to make into a pool bucket
  1319.  * @param buf The buffer to insert into the bucket
  1320.  * @param length The number of bytes referred to by this bucket
  1321.  * @param pool The pool the memory was allocated from
  1322.  * @return The new bucket, or NULL if allocation failed
  1323.  */
  1324. APU_DECLARE(apr_bucket *) apr_bucket_pool_make(apr_bucket *b, const char *buf,
  1325.                                                apr_size_t length, 
  1326.                                                apr_pool_t *pool);
  1327.  
  1328. #if APR_HAS_MMAP
  1329. /**
  1330.  * Create a bucket referring to mmap()ed memory.
  1331.  * @param mmap The mmap to insert into the bucket
  1332.  * @param start The offset of the first byte in the mmap
  1333.  *              that this bucket refers to
  1334.  * @param length The number of bytes referred to by this bucket
  1335.  * @param list The freelist from which this bucket should be allocated
  1336.  * @return The new bucket, or NULL if allocation failed
  1337.  */
  1338. APU_DECLARE(apr_bucket *) apr_bucket_mmap_create(apr_mmap_t *mm, 
  1339.                                                  apr_off_t start,
  1340.                                                  apr_size_t length,
  1341.                                                  apr_bucket_alloc_t *list);
  1342.  
  1343. /**
  1344.  * Make the bucket passed in a bucket refer to an MMAP'ed file
  1345.  * @param b The bucket to make into a MMAP bucket
  1346.  * @param mmap The mmap to insert into the bucket
  1347.  * @param start The offset of the first byte in the mmap
  1348.  *              that this bucket refers to
  1349.  * @param length The number of bytes referred to by this bucket
  1350.  * @return The new bucket, or NULL if allocation failed
  1351.  */
  1352. APU_DECLARE(apr_bucket *) apr_bucket_mmap_make(apr_bucket *b, apr_mmap_t *mm,
  1353.                                                apr_off_t start, 
  1354.                                                apr_size_t length);
  1355. #endif
  1356.  
  1357. /**
  1358.  * Create a bucket referring to a socket.
  1359.  * @param thissocket The socket to put in the bucket
  1360.  * @param list The freelist from which this bucket should be allocated
  1361.  * @return The new bucket, or NULL if allocation failed
  1362.  */
  1363. APU_DECLARE(apr_bucket *) apr_bucket_socket_create(apr_socket_t *thissock,
  1364.                                                    apr_bucket_alloc_t *list);
  1365. /**
  1366.  * Make the bucket passed in a bucket refer to a socket
  1367.  * @param b The bucket to make into a SOCKET bucket
  1368.  * @param thissocket The socket to put in the bucket
  1369.  * @return The new bucket, or NULL if allocation failed
  1370.  */
  1371. APU_DECLARE(apr_bucket *) apr_bucket_socket_make(apr_bucket *b, 
  1372.                                                  apr_socket_t *thissock);
  1373.  
  1374. /**
  1375.  * Create a bucket referring to a pipe.
  1376.  * @param thispipe The pipe to put in the bucket
  1377.  * @param list The freelist from which this bucket should be allocated
  1378.  * @return The new bucket, or NULL if allocation failed
  1379.  */
  1380. APU_DECLARE(apr_bucket *) apr_bucket_pipe_create(apr_file_t *thispipe,
  1381.                                                  apr_bucket_alloc_t *list);
  1382.  
  1383. /**
  1384.  * Make the bucket passed in a bucket refer to a pipe
  1385.  * @param b The bucket to make into a PIPE bucket
  1386.  * @param thispipe The pipe to put in the bucket
  1387.  * @return The new bucket, or NULL if allocation failed
  1388.  */
  1389. APU_DECLARE(apr_bucket *) apr_bucket_pipe_make(apr_bucket *b, 
  1390.                                                apr_file_t *thispipe);
  1391.  
  1392. /**
  1393.  * Create a bucket referring to a file.
  1394.  * @param fd The file to put in the bucket
  1395.  * @param offset The offset where the data of interest begins in the file
  1396.  * @param len The amount of data in the file we are interested in
  1397.  * @param p The pool into which any needed structures should be created
  1398.  *          while reading from this file bucket
  1399.  * @param list The freelist from which this bucket should be allocated
  1400.  * @return The new bucket, or NULL if allocation failed
  1401.  */
  1402. APU_DECLARE(apr_bucket *) apr_bucket_file_create(apr_file_t *fd,
  1403.                                                  apr_off_t offset,
  1404.                                                  apr_size_t len, 
  1405.                                                  apr_pool_t *p,
  1406.                                                  apr_bucket_alloc_t *list);
  1407.  
  1408. /**
  1409.  * Make the bucket passed in a bucket refer to a file
  1410.  * @param b The bucket to make into a FILE bucket
  1411.  * @param fd The file to put in the bucket
  1412.  * @param offset The offset where the data of interest begins in the file
  1413.  * @param len The amount of data in the file we are interested in
  1414.  * @param p The pool into which any needed structures should be created
  1415.  *          while reading from this file bucket
  1416.  * @return The new bucket, or NULL if allocation failed
  1417.  */
  1418. APU_DECLARE(apr_bucket *) apr_bucket_file_make(apr_bucket *b, apr_file_t *fd,
  1419.                                                apr_off_t offset,
  1420.                                                apr_size_t len, apr_pool_t *p);
  1421.  
  1422. #if APR_HAS_MMAP
  1423. /**
  1424.  * Enable or disable memory-mapping for a FILE bucket (default is enabled)
  1425.  * @param b The bucket
  1426.  * @param enable Whether memory-mapping should be enabled
  1427.  * @return APR_SUCCESS normally, or an error code if the operation fails
  1428.  */
  1429. APU_DECLARE(apr_status_t) apr_bucket_file_enable_mmap(apr_bucket *b,
  1430.                                                       int enabled);
  1431. #endif /* APR_HAS_MMAP */
  1432.  
  1433. /** @} */
  1434. #ifdef __cplusplus
  1435. }
  1436. #endif
  1437.  
  1438. #endif /* !APR_BUCKETS_H */
  1439.